All Databases Inside Mac - AppleEvents

AESend

Send an Apple Event

#include <AppleEvents.h> Apple Event Manager

OSErr AESend ( theAppleEvent, reply, sendMode, sendPriority,

timeOutInTicks, idleProc, filterProc );

AppleEvent * theAppleEvent ; Apple Event to send

AppleEvent * reply ; reply Apple Event which is returned

AESendMode sendMode ; see below

AESendPriority sendPriority ; back or front of queue

long timeOutinTicks ; time to wait for user response

IdleProcPtr idleProc ; pointer to your idle function

EventFilterProcPtr filterProc ; pointer to filter function

returns Error Code; 0 = no error

The AESend function sends an Apple event.

The parameter theAppleEvent specifies the Apple event to be sent.

The reply parameter specifies the reply Apple event that is returned if you

specify the kAEWaitReply flag in the sendMode parameter. (If you specify the

kAEQueueReply flag in the sendMode parameter, you receive the

reply Apple event in your event queue.) If you specify either the

kAEQueueReply flag or the kAENoReply flag, the data in the

reply Apple event returned by this function is not valid. If this function

returns a nonzero result, it also returns in the reply parameter a descriptor

record whose descriptor type is typeNull-that is, one that does not contain

data. If you specify kAEWaitReply, your application is responsible for using

the AEDisposeDesc function to dispose of the resulting descriptor record.

The sendMode parameter allows you to specify the following: the reply mode

for the Apple event (set with one of the constants kAENoReply, kAEQueueReply,

or  kAEWaitReply); the interaction mode (set with one of the  constants
 kAENeverInteract,  kAECanInteract, or  kAEAlwaysInteract); the layer switch
mode (set with the  kAECanSwitchLayer  constant); the reconnection mode (set
with the kAEDontReconnect  constant); and the return receipt mode (set with

the kAEWantReceipt constant). You obtain the value for this parameter by

adding the appropriate constants. These flags are stored in the interaction level

attribute, whose keyword is keyInteractLevelAttr.

In the sendPriority parameter, you specify flags that determine whether the

Apple event is put at the back of the event queue (the kAENormalPriority flag)

or at the front of the queue (the kAEHighPriority flag).

If the reply mode specified in the sendMode parameter is kAEWaitReply, or if

a return receipt is requested, the timeOutInTicks parameter specifies the

length of time (in ticks) that the client application is willing to wait for the

reply or return receipt from the server application before timing out. Most

applications should use the kAEDefaultTimeout constant, which tells the

Apple Event Manager to provide an appropriate timeout duration. If the

value of this parameter is kNoTimeOut, the Apple event never times out.

The idleProc parameter specifies a pointer to a function for any tasks (such

as displaying a wristwatch or spinning beach ball cursor) that the application

performs while waiting for a reply or a return receipt.

The filterProc parameter specifies a pointer to a routine that accepts certain

incoming Apple events that are received while the handler waits for a reply or

a return receipt and filters out the rest.

You can use one of the flags discussed above in the sendMode parameter to

specify the reply mode for an Apple event. Only one of these flags may be set.

For a list of these, see the Apple Event Manager Data.

If the Apple Event Manager cannot find a handler for an Apple event in

either the application or system Apple event dispatch table, it returns the

result code errAEEventNotHandled to the server application (as the result of

the AEProcessAppleEvent function). If the client is waiting for a reply, the

Apple Event Manager also returns this result code to the client.

AESend returns noErr as the function result if the Apple event was

successfully sent by the Event Manager. A noErr result from AESend does not

indicate that the Apple event was handled successfully; it only indicates that

the Apple event was successfully sent by the Event Manager. If a result code

other than noErr is returned by the handler, and if the client is waiting for a

reply, it is returned in the keyErrorNumber parameter of the reply Apple

event.

Result codes

noErr (0) No error

memFullErr (-108) Not enough room in heap zone

connectionIn valid (-609) Connection is in valid

errAEEventNotHandled (-1708) Event wasn't handled by an Apple event

handler

errAEUnknownSendMode (-1710) Invalid sending mode was passed

errAEWaitCanceled (-1711) User canceled out of wait loop for reply

or receipt

errAETimeout (-1712) Apple event timed out

errAEUnknownAddressType (-1716) Unknown Apple event address type

Referenced by (48):